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Why use OpenBSD? 

“Only one remote hole in the default install, in more than 7 years” 

• A purpose built secure operating system. 

• Rich, off the shelf firewall functionality. 

• Proactive security stance. 

• High performance. 

• Strong standards compliance. 

• Open source and free. 

• A history of regular releases and improvements. 

• An active user community. 

J) 
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Firewall Building Blocks 


• A security policy. What should the firewall do? 

• The pf packet filter. 

• The ftp-proxy(8) proxy. 

• The authpf(8) shell. 

• The ssh( 1) shell. 

An OpenBSD firewall can also act as an IPSEC endpoint. 




















What is PF? 


Pf is OpenBSD’s kernel based packet filter: 

• Layer 3 and 4 filtering. 

• Stateful inspection. 

• Traffic normalisation. 

• Bandwidth control. 

• Network address translation. 

• Transparent proxying. 

• Full IPv4 and IPv6 support. 



Configuration 

Pf is enabled by editing /etc/rc. conf. This causes the ruleset 
to be loaded at boot time, and for pflogd(8) to be run as a daemon. 

Rulesets are conventionally stored in /etc/pf.conf. 

Rulesets may be manually loaded using pfctl(l): 

pfctl -Fall -f /etc/rc.conf 

The pfctl(l) has many other useful control and monitoring 
functions. 













Structure of pf.conf 


1. Macro definitions. 

2. Table definitions. 

3. Engine options. 

4. Traffic normalisation rules. 

5. Queueing rules. 

6. Address translation rules. 

7. Packet filtering rules. 
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Packet Filtering Rules 



The basic format of a filter rule is: 

action [direction] [logging] [quick] [interface] [route] 
[address-family] [protocol] hosts [miscellaneous] 

• Rules are evaluated in sequential order, for each packet. 

• The last matching rule determines the action taken. 

• If no rule matches the packet, the default action is permit the 
packet to pass through the filter. 
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Actions 


pass 

The packet is permitted to proceed, 
block [return-option] 

The packet is blocked. Several return options are supported: 

• drop 

Drop the packet silently. This is the default behaviour. 

• retum-rst [ ( ttl-number)] 

Return a TCP RST segment (applies only to TCP packets). 

The TTL may be specified (defaults to 64), which may 
make the firewall less visible. 

i -J 
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Actions (Continued) 


return-icmp [(icmpcode [, icmp6code])] 

Return an ICMP packet (by default, of type 
UNREACHABLE). A specific ICMP integer code may be 
specified, and distinct codes may be returned for IPv4 and 
IPv6 traffic. 

return-icmp6 [ (icmp6code)] 

Similar to return-icmp, but applying only to IPv6 
packets. 

return 

Return a TCP RST segment for TCP packets, an ICMP 
UNREACHABLE for UDP packets, and drops all other 
packets silently. 
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Symbolic ICMP Codes 




ICMP return codes may be specified as strings, which generate 
ICMP packets of an appropriate type. 

ICMPv6 Return Codes 




String Code 

ICMP Type 

admin-unr, noroute-unr, notnbr-unr, 
beyond-unr, addr-unr, port-unr, 

destination unreachable 

transit, reassemb 

time exceeded 

badhead, nxthdr 

parameter problem 

redironlink, redirrouter 

neighbor discovery redirect 
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Symbolic ICMP Codes (Continued) 


ICMPv4 Return Codes 


String Code 

ICMP Type 

net-unr, host-unr, proto-unr, port-unr, 
needfrag, srcfail, net-unk, host-unk, 
isolate, net-prohib, host-prohib, net-tos, 
host-tos, filter-prohib, host-preced, 
cutoff-preced 

unreachable 

redir-net, redir-host, redir-tos-net, 
redir-tos-host 

redirect 

normal-adv, common-adv 

router advertisment 

transit, reassemb 

time exceeded 

badhead, optmiss, badlen 

parameter problem 

unknown-ind, auth-fail, decrypt-fail 

photuris 
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Some Simple Blocking Rules 

A good first rule is usually: 

block return all 

If you want to be a little more stealthy: 

block all 

block return-rst proto top from any to any port auth 


If you want to be a little different: 

block return-icmp(filter-prohib, admin-unr) all 
block return-rst(4) proto tcp 
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Packet Direction 


Rules may have an associated direction: 


in 


Matches packets inbound from an interface. 

out 

Matches outbound to an interface. 

If direction is not specified, both inbound and outbound packets 
are matched. 

For example: 

block return in all 
pass out all 
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Host Specification 

All rules must specify the source and destination of the packet. 
The general form is: 

from host to host 

A host may be: 

• An IPv4 or IPv6 numeric address (e.g. 127.0.0.1 or ::1). 

• An IPv4 or IPv6 netblock (e.g. 10.0.0.0/8 or fec0::/80). 

• A DNS name. 

• An interface name. 
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Host Specification (Continued) 


An interface name followed by a netmask (e.g. deO/24). 

An interface name enclosed in parentheses (e.g. (deO)). 

An interface name followed by “:network” (e.g. deO:network). 

An interface name followed by “:broadcast” (e.g. 
deO:broadcast). 

A list of hosts, of the form: {host ,...} 



Special Host Names 

Special host names help make a ruleset more portable. 

any 

Matches any address. 

no-route 

Matches any address that cannot be routed to. If you have a 
default route, this will never match. 

self 

Matches any of the addresses, on any of the local interfaces. 
In addition, the special string “all” is shorthand for: 

from any to any 
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Host Specification Examples 

Host specification: 

pass in from any to self 
pass in from 10.0.0.1 to any 
pass in from fec0::l to any 

pass in from deOrnetwork to {10.0.0.1, 10.0.0.2} 

Netblock specification: 

pass in from 10.0.0.0/8 to 192.168.0.0/16 
pass in from fecO:0:0:0::/64 to fecO:0:0:1::/64 
pass in from de0/80 to fec0::/80 
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Use of Hostnames Considered Harmful 


Hostnames are resolved when the ruleset is loaded into the 
kernel. 

• What if the DNS is unavailable when you configure? 

• What if a DNS record is changed after you load the ruleset? 

• What if the DNS is subverted? 

Recommendation: Use only numeric host specifications in your 
rulesets for better security and reliability. 
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Host Negation 


Sources and destinations may be negated with a preceding “!”. 
This is useful for filtering everything but a given host or netblock. 

# anything but non-routable 
pass in from !no-route to any 

# anything but RFC 1918 addresses 


pass 

in 

from 

110.0.0. 

0/8 to any 

pass 

in 

from 

!172.31. 

0.0/12 to any 

pass 

in 

from 

1192.168 

.0.0/16 to any 


# anything but link-local and site-local 
pass in from {!fe80::/10, !fec0::/10} to any 



Protocol Specification 

Packets of a specific protocol may be matched with a constraint of 
the form: 

proto protocol 

A protocol is a protocol number, a name from /etc/protocols or 
a list of the form: { protocol ,...}. 

For example: 

# allow VPN protocols 

pass in proto {ah, esp, 12tp} from any to 10.0.0.1 
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Port Specification 

TCP and UDP packets may be matched for source and destination 
ports with a host constraint of the form: 

port port 

A port is a port number, a name from /etc/services, or a list of 
the form: {port ,...}. 

For example: 

# allow public services 
pass in proto top from any 

to 10.0.0.1 port {ssh, smtp, www} 



Port Ranges 

Port ranges may be specified using operators: 

unary-operator port 
port binary-operator pert 

The unary operators are: =, ! =, <, <=, > and >=. 

The binary operators are <>, x. 

For example: 

pass in proto udp from any port = domain to any 
pass in from any port < 1024 to any 
pass in proto top from any 

to any port 49151 >< 57345 




-4 
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Address Family Specification 


Packets of a specific address family may be matched with an 
address family constraint: 

inet 

IPv4 packets 

inet6 

IPv6 packets 
For example: 

# allow all IPv6 traffic between deO and del networks 
pass in inet6 from deO:network to del:network 




Interface Specification 

Packets arriving or departing on a specific interface may be 
matched with an interface constraint: 

on interface 

An interface is an interface name, or a list of interfaces of the 
form: { interface , ...}. 

An interface may be negated by a preceding 
For example: 

pass in on {!deO, !del} all 

pass in on deO from 110.0.0.0/8 to any 
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Routing 

Special routing is enabled by adding a routing specification: 

fastroute 

Immediately route packet, according to routing tables. 

route-to destination 

Route packet to the specified destination. 

dup-to destination 

Duplicate packet to the specified destination. 

A destination is an interface name. The next hop addresses may 
be optionally specified with a destination of the form: (interface 
address). 
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Routing Examples 

# fast routing 

pass in fastroute from any to 10.0.0.1 port 80 

# specialized routing 

pass in route-to (deO 192.168.0.1) 
from any to 10.0.0.0/8 
pass in route-to (deO 192.168.0.2) 
from any to 10.0.0.0/24 

# duplicate all blocked traffic 
block in dup-to de9 all 



Quick Rules 

Ruleset processing may be short circuited by marking a rule with 
the “quick” keyword. 

Quick rules, if matched, terminate ruleset processing 
immediately. 

For example: 

# antispoof deO 

block in log quick on deO from 110.0.0.0/8 to any 

# trust loO totally 
pass in quick on loO 


30 













TCP Flags 


TCP packets with specific flags may be matched with a constraint 
of the form: 


flags set-flags/flag-set 

The TCP flags are (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, 
(E)CE, and C(W)R. 

For example: 


# allow outgoing top connections 

pass in proto top from 10.0.0.0/8 to any 

pass in proto top from any to 10.0.0.0/8 flags /S 

pass in proto top from any to 10.0.0.0/8 flags SA/SA 
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ICMP Types 

ICMP packets of a specific type and code may be matched with 
constraints of the form: 

icmp-type type [code code] 
icmp6-type type [code code] 

Types and codes may be specified numerically or symbolically. 
For example: 

pass in inet proto icmp from 10.0.0.0/8 to any 
icmp-type echoreq 

pass in inet proto icmp from any to 10.0.0.0/8 
icmp-type echorep 
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ICMPv4 Types and Codes 

ICMPv4 types: 

echoreq, echorep, unreach, squench, redir, althost, routeradv, 
routersol, timex, paramprob, timereq, timerep, inforeq, 
inforep, maskreq, maskrep, trace, dataconv, mobredir, 
ipv6-where, ipv6-here, mobregreq, mobregrep, skip, photuris 

ICMPv4 codes: 

net-unr, host-unr, proto-unr, port-unr, needfrag, srcfail, 
net-unk, host-unk, isolate, net-prohib, host-prohib, net-tos, 
host-tos, filter-prohib, host-preced, cutoff-preced, redir-net, 
redir-host, redir-tos-net, redir-tos-host, normal-adv, 
common-adv, transit, reassemb, badhead, optmiss, badlen, 
unknown-ind, auth-fail, decrypt-fail 




ICMPv6 Types and Codes 

ICMPv6 types: 

unreach, toobig, timex, paramprob, echoreq, echorep, 
groupqry, listqry, grouprep, listenrep, groupterm, listendone, 
routersol, routeradv, neighbrsol, neighbradv, redir, 
routrrenum, wrureq, wrurep, fqdnreq, fqdnrep, niqry, nirep, 
mtraceresp, mtrace, 

ICMPv6 codes: 

admin-unr, noroute-unr, notnbr-unr, beyond-unr, addr-unr, 
port-unr, transit, reassemb, badhead, nxthdr, redironlink, 
redirrouter, 
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Users and Groups 


When an endpoint of a TCP or UDP connection is a local socket, 
the user and/or group of the socket may be selected for with a 
constraints of the form: 

user uid 
group gid 

User and group id’s may be numeric or as defined in 
/etc/passwd and /etc/group. Packets with no local socket 
have a user and group of “unknown”. 

For example: 

pass in from any to any port ssh user root 
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IP Fragments 


By default, only rules that apply solely to IP header fields apply 
to fragments. 

Fragments may be explicitly matched with a qualification of the 
form 

fragment 

For example: 

pass in from 10.0.0.0/8 port 80 to any fragment 

All IPv6 fragments are blocked unconditionally. 

i -i 
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Labels 


Rules may be assigned labels, which are useful for later 
identification. Labels are defined with a qualification of the form: 


label ’’string” 

Label strings support the following configuration-time macros: 

$if, $srcaddr, $srcport, $dstaddr, $dstport, $proto and $nr. 

For example: 


pass in from any to {10.0.0.1, 10.0.0.2} 

label "any->$dstaddr" 


The command “pfctl -s” shows statistics for all labelled rules. 


J 
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Stateful Protocols 

Stateful TCP processing includes: 

• Sequence number tracking. 

• Connection state tracking. 

• Timeouts for abandoned connections. 
Stateful UDP processing includes: 

• Timeouts for abandoned connections. 
Stateful ICMP processing includes: 

• Return type matching. 

• Timeouts for abandoned connections. 
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Stateful Examples 


# a stateful tcp connection 
pass in proto tcp from any 

to 10.0.0.1 port ssh flags S/SAFR keep state 

# a stateful udp connection 

pass in proto udp from 10.0.0.0/8 
to any port domain keep state 

# a stateful icmp connection 

pass in proto icmp from 10.0.0.0/8 
to any keep state 
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State Modulation 

Many common TCP stacks choose poor Initial Sequence Numbers 
(ISN’s), and are suscpetible to ISN prediction exploits. 

State modulation is enabled by a rule of the form: 

pass ... modulate state 

For example: 


pass in proto tcp from 10.0.0.0/8 to any 
flags S/SAFR modulate state 
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State Timeouts 


The supported timeout variables are: 

• tcp.first, tcp.opening, tcp.established, tcp.closing, 
tcp.finwait, tcp.closed. 

• udp.first, udp.single, udp.multiple 

• icmp.first, icmp.error 

• other.first, other.single, other.multiple 

For example: 

pass in proto top from 10.0.0.0/8 to any 
keep state (max 100, tcp.first 30) 



Stateful Logging 

A standard logging rule only logs the first packet of a stateful 
connection. 

To log the entire connection, use the “log-all” keyword instead. 
For example: 

pass in log-all proto tcp from any 

to 10.0.0.1 port ssh flags S/SAFR keep state 
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Stateful Routing 

A rule of the form: 

pass ... route-to ... keep state 

routes all the packets for a connection, travelling in one direction. 

To route backchannel packets, use a mile of the form: 

pass ... reply-to ... keep state 

This can be used to enforce symmetrical routing. For example: 

pass in on deO reply-to deO proto top from any to any 
keep state 
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Antispoofing 

Antispoof directives expand to rules which prevent packets with a 
source address belonging to any directly connected network from 
arriving on an incorrect interface. 

antispoof [logging] [quick] for interface 

For example: 

antispoof for loO 

is expanded to: 

block drop in on !loO inet from 127.0.0.1/8 to any 
block drop in on !lo0 inet6 from ::1 to any 
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Traffic Normalisation (Continued) 

random-id 

Replaces the IP identification field with a random number. 

fragment reassemble 

Reassembles packets before processing. 

fragment crop 

Tracks fragments, dropping duplicates and cropping overlaps. 

fragment drop-ovl 

Tracks fragments, dropping duplicates and overlaps. 

For example: 

scrub in on deO all fragment reassemble 
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Bandwidth Control 

Queues are used to implement bandwidth control on outbound 
packets. Queueing is enabled on an interface with a statement of 
the form: 

altq on interface scheduler [interface-options] 
queue {queue-name,...} 

Schedulers determine the order in which packets are transmitted 
or discarded. The supported schedulers are: 

priq 

Strict priority queuing. 

cbq 

Class based queueing. 
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/f=== 

Interface Options 



bandwidth numberfunits] 

Specifies the maximum bitrate for all queues on the interface 
(defaults to the interface’s bitrate). May optionally specify 
units: “b”, “Kb”, “Mb”, “Gb” or 

qlimit number 

Specifies the maximum number of packets to be queued on 
this interface (defaults to 50 ). 

tbrsize number 

Specifies the number of bytes in the token bucket regulator 
(defaults to something reasonable, based on the interface’s 
bandwidth). 
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Defining Queues 


Queues are defined by a directive of the form: 

queue name [options] [scheduler ( parameter, ...)] 
/queue {child, ...}] 

The supported options are: 

bandwidth number[units] 

The maximum bitrate of the queue (cbq only). 

priority level 

The priority of the queue (default 1). 

qlimit limit 

The maximum number of packets in the queue (default 50). 











More Scheduler Parameters 


ecn 


Enable Explicit Congestion Notification (RFC 3168). ECN 
signals congestion in the ECN IP header, allowing peers that 
support this mechanism to throttle before packet loss. Implies 
RED. 


borrow 

Enable bandwidth borrowing (cbq only). Unused bandwidth 
from a parent queue may be temporarily used by a child. 
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Queue Definition Examples 

# priq scheduler queues 
queue deO_high priority 1 

queue deO_std priority 0 priq(default) 

# cbq scheduler queues 

queue del_std priority 3 cbq(default) 
queue {del_devel, del_sales} 
queue del_high priority 7 
queue del_bulk priority 0 cbq(red) 
queue del_devel bandwidth 60% cbq(borrow) 
queue del_sales bandwidth 40% 
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Assigning Packets to Queues 


Packets are assigned to queues by adding a queue specification to 
a filter rule, of the form: 

queue queue-name 

An alternate form allows packets with a TOS of “lowdelay” and 
TCP ACK packets with no payload to be queued seperately: 

queue ( normal-queue, low delay-queue) 

When applied to “block” rules, the queue specification applies to 
the returned ICMP packet or TCP RST (if any). 
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Packet Assignment Examples 


# priq scheduler 

pass out on deO all queue (deO_std, deO_high) 

# cbq scheduler 

pass out on del from any to 10.0.0.0/24 
queue (del_devel, del_high) 
pass out on del from any to 10.0.1.0/24 
queue (del_sales, del_high) 
pass out on del proto tcp from any to any port smtp 
queue del_bulk 











Network Address Translation 


Network address translation is enabled by a rule of the form: 

[no] nat [interface] [address-family] [protocol] hosts 
-> address [options] 


Address is a host address or netblock, with syntax as per filter 
rules. 


NAT is often used to map internal RFC 1918 addresses to a single 
external interface address. 

For example: 


nat on !deO inet from 10.0.0.0/8 to any -> deO 
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Bidirectional NAT 

Two network blocks may be bidirectionally mapped by a rule of 
the form: 

[no] binat [interface] [address-family] [protocol] 
from address -> address 

Bidirectional network address translation is often used when 
networks with overlapping address space need to interoperate. 

For example: 

binat on deO inet from 10.0.0.0/8 -> 192.0.0.0/16 
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Redirection 


Packets may be redirected by a rule of the form: 

[no] rdr [interface] [address-family] [protocol] hosts 
-> address [port] [options] 

Redirection is useful for moving or load balancing services. 
For example: 

rdr on deO proto top from any to any port 80 
-> 127.0.0.1 port 80 



Redirecting Port Ranges 


An entire port range may be redirected thus: 

rdr on deO proto top from any to any port 8000:8999 
-> 127.0.0.1 port 80 


Multiple destination ports may be declared: 

rdr on deO proto top from any to any port 8000:8999 
-> 127.0.0.1 port 20000:* 











Address Pool Options 



There are several address pool options which apply to nat and 
rdr rules: 

bitmask 

Applies the network portion of the redirection address to the 
address to be modifed. 

random 

Selects a redirection address at random, 
source-hash [key] 

Hashes the source address to determine the redirection 
address. 



Address Pool Options (Continued) 

round-robin 

Cycles through the redirection addresses, in order. 

static-port 

Prevents the source port from being modified. 

For example: 

rdr on deO proto top from any to 10.0.0.1 port 80 
-> {10.0.1.1, 10.0.1.2, 10.0.1.3} round-robin 
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Tables 


A table may be used instead of a list of addresses: 

table <name> [attribute] [{address, ...}] 

The support attributes are: 

persist 

The table is kept even when no rules refer to it. 

const 

The table may not be changed at run-time. 

For example: 

table <rfcl918> const {10/8, 172.16/12, 192.168/16} 
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File Tables 

Tables may be initialised from a file: 

table <name> [attribute] /file "path”...] 

For example: 

table <spamxners> persist 

file "/etc/spammers" file "/etc/openrelays" 

Lines beginning with “#” are ignored in table files. 
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Macros 





Macros may defined to assist in the configurability and 
readability of rulesets. 

macro - value 

Macros usage is signalled by a leading Macros are not 
exapnded inside quotes. 

For example: 

if_external = deO 

pass in on $if_external proto top from any 
to 10.0.0.1 port 80 keep state 



Anchors 

A ruleset may contain anchor points : 

nat-anchor name binat-anchor name rdr-anchor name 

anchor name 

Each anchor may have zero or more sub-rulesets loaded into it via 
pfctl(l). Sub-rulesets in an anchor are evaluated in lexical name 
order. 
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Anchor Example 


In the main ruleset: 

# execute spam rules 
anchor spamrules 

Dynamic updating of anchor: 

pfctl -a spamrules:blackhole -F rules 
-f /etc/pf.blackhole 
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Performance Tuning 

• Use quick rules (carefully). 

• Use stateful filtering for connections. 

• Use tables for large groups of addresses. 

• Use “aggressive” optimisation. 

• Minimise logging (or log to another machine). 













FTP Proxy 



FTP connections may be handled by ftp-proxy(8), which expects to 
be redirected control connections from pf: 

rdr proto top from ant to any port 21 
-> 127.0.0.1 port 8021 

The ftp-proxy process is configured in /etc/inetd. conf like 
this: 

127.0.0.1:8021 stream top nowait root 
/usr/libexec/ftp-proxy ftp-proxy 



Authenticating Shell 

The authpf(8) shell may be used to add packet filter rules when a 
user logs in, and remove then when they log out. This is achieved 
via the special anchor “authpf”. 

Ssh(l) may therefore be used as a strong authentication 
mechanism before allowing packet level access to a network. In 
addition, specific rules may be defined for each user, thus 
providing fine grained access control. 

Rules loaded by authpf(8) may use the macros $user Jd and 
$user jp. 
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PF.CONF (5) 


OpenBSD Programmer’s Manual 


PF.CONF (5) 


Tables can be used as the source or destination of filter rules, scrub rules or translation rules such as nat or 
rdr (see below for details on the various rule types). Tables cannot be used for things like the redirect ad¬ 
dress of translation rules, nor can they be used in the routing options of filter rules. 

Tables can be defined with any of the following pfctl(8) mechanisms. As with macros, reserved words 
may not be used as table names. 

manually Persistent tables can be manually created with the add or replace option of pfctl(8), be¬ 
fore or after the ruleset has been loaded. 

pf. conf Table definitions can be placed directly in this file, and loaded at the same time as other rules 
are loaded, atomically. Table definitions inside pf .conf use the table statement, and are 
especially useful to define non-persistent tables. The contents of a pre-existing table defined 
without a list of addresses to initialize it is not altered when pf. conf is loaded. A table ini¬ 
tialized with the empty list, { }, will be cleared on load. 

Tables may be defined with the following two attributes: 

persist The persist flag forces the kernel to keep the table even when no rules refer to it. If the flag is 
not set, the kernel will automatically remove the table when the last rule referring to it is flushed. 

const The const flag prevents the user from altering the contents of the table once it has been created. 

Without that flag, pfctl(8) can be used to add or remove addresses from the table at any time, 
even when running with securelevel(7) = 2. 

For example, 

table <private> const { 10/8, 172.16/12, 192.168/16 } 
table <badhosts> persist 

block on fxpO from { <private>, <badhosts> } to any 

creates a table called private, to hold RFC 1918 private network blocks, and a table called badhosts, which is 
initially empty. A filter rule is set up to block all traffic coming from addresses listed in either table. The pri¬ 
vate table cannot have its contents changed and the badhosts table will exist even when no active filter rules 
reference it. Addresses may later be added to the badhosts table, so that traffic from these hosts can be 
blocked by using 

# pfctl -t badhosts -Tadd 204.92.77.111 

A table can also be initialized with an address list specified in one or more external files, using the following 
syntax: 

table <spam> persist file "/etc/spammers" file "/etc/openrelays" 
block on fxpO from <spam> to any 

The files /etc/spammers and /etc/openrelays list IP addresses, one per line. Any lines beginning 
with a # are treated as comments and ignored. In addition to being specified by IP address, hosts may also be 
specified by their hostname. When the resolver is called to add a hostname to a table, all resulting IPv4 and 
IPv6 addresses are placed into the table. IP addresses can also be entered in a table by specifying a valid in¬ 
terface name or the self keyword, in which case all addresses assigned to the interface(s) will be added to the 
table. 

OPTIONS 

pf (4) may be tuned for various situations using the set command. 

set timeout 
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interval Interval between purging expired states and fragments. 
frag Seconds before an unassembled fragment is expired. 

When a packet matches a stateful connection, the seconds to live for the connection will be updated to 
that of the proto .modi fier which corresponds to the connection state. Each packet which 
matches this state will reset the TTL. Tuning these values may improve the performance of the fire¬ 
wall at the risk of dropping valid idle connections. 

tcp.first 

The state after the first packet. 

tcp. opening 

The state before the destination host ever sends a packet. 
tcp.established 

The fully established state. 

tcp.closing 

The state after the first FIN has been sent. 

tcp.finwait 

The state after both FINs have been exchanged and the connection is closed. Some hosts (no¬ 
tably web servers on Solaris) send TCP packets even after closing the connection. Increasing 
tcp. finwait (and possibly tcp. closing) can prevent blocking of such packets. 
tcp.closed 

The state after one endpoint sends an RST. 

ICMP and UDP are handled in a fashion similar to TCP, but with a much more limited set of states: 

udp.first 

The state after the first packet. 

udp.single 

The state if the source host sends more than one packet but the destination host has never sent 
one back. 

udp.multiple 

The state if both hosts have sent packets. 

icmp.first 

The state after the first packet. 

icmp.error 

The state after an icmp error came back in response to an icmp packet. 

Other protocols are handled similarly to UDP: 

other.first 
other.single 
other.multiple 

For example: 

set timeout tcp.established 3600 

set timeout { tcp.opening 30, tcp.closing 900 } 

set loginterface 

Enable collection of packet and byte count statistics for the given interface. These statistics can be 
viewed using 

# pfctl -s info 

In this example pf (4) collects statistics on the interface named dcO: 
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set loginterface dcO 

One can disable the loginterface using: 

set loginterface none 

set limit 

Sets hard limits on the memory pools used by the packet filter. See pool(9) for an explanation of 
memory pools. 

For example, 

set limit states 20000 

sets the maximum number of entries in the memory pool used by state table entries (generated by 
keep state rules) to 20000. Using 

set limit frags 20000 

sets the maximum number of entries in the memory pool used for fragment reassembly (generated by 
scrub rules) to 20000. 

These can be combined: 

set limit { states 20000, frags 20000 } 
set optimization 

Optimize the engine for one of the following network environments: 

normal 

A normal network environment. Suitable for almost all networks. 

high-latency 

A high-latency environment (such as a satellite connection). 

satellite 

Alias for high-latency, 
aggressive 

Aggressively expire connections. This can greatly reduce the memory usage of the firewall at 
the cost of dropping idle connections early. 

conservative 

Extremely conservative settings. Avoid dropping legitimate connections at the expense of 
greater memory utilization (possibly much greater on a busy network) and slightly increased 
processor utilization. 

For example: 

set optimization aggressive 
set block-policy 

The block-policy option sets the default behaviour for the packet block action: 
drop Packet is silently dropped. 

return A TCP RST is returned for blocked TCP packets, an ICMP UNREACHABLE is re¬ 
turned for blocked UDP packets, and all other packets are silently dropped. 

For example: 

set block-policy return 
set require-order 

By default pfctl(8) enforces an ordering of the statement types in the ruleset to: options , 
normalization , queueing , translation, filtering. Setting this option to no disables this enforcement.^ 
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There may be non-trivial and non-obvious implications to an out of order ruleset. Consider carefully 
before disabling the order enforcement. 

TRAFFIC NORMALIZATION 

Traffic normalization is used to sanitize packet content in such a way that there are no ambiguities in packet 
interpretation on the receiving side. The normalizer does IP fragment reassembly to prevent attacks that con¬ 
fuse intrusion detection systems by sending overlapping IP fragments. Packet normalization is invoked with 
the scrub directive. 

scrub has the following options: 

no-df 

Clears the dont-fragment bit from a matching ip packet. Some operating systems are known to 
generate fragmented packets with the dont-fragment bit set. This is particularly true with NFS. 
Scrub will drop such fragmented dont-fragment packets unless no-df is specified. 

Unfortunately some operating systems also generate their dont-fragment packets with a zero IP 
identification field. Clearing the dont-fragment bit on packets with a zero IP ID may cause dele¬ 
terious results if an upstream router later fragments the packet. Using the random-id modifier (see 
below) is recommended in combination with the no-df modifier to ensure unique IP identifiers. 

min-ttl <number> 

Enforces a minimum ttl for matching ip packets. 

max-mss <number> 

Enforces a maximum mss for matching tcp packets. 

random-id 

Replaces the IP identification field with random values to compensate for predictable values generat¬ 
ed by many hosts. This option only applies to outgoing packets that are not fragmented after the op¬ 
tional fragment reassembly. 

fragment reassemble 

Using scrub rules, fragments can be reassembled by normalization. In this case, fragments are 
buffered until they form a complete packet, and only the completed packet is passed on to the filter. 
The advantage is that filter rules have to deal only with complete packets, and can ignore fragments. 
The drawback of caching fragments is the additional memory cost. But the full reassembly method is 
the only method that currently works with NAT. This is the default behavior of a scrub rule if no 
fragmentation modifier is supplied. 

fragment crop 

The default fragment reassembly method is expensive, hence the option to crop is provided. In this 
case, pf(4) will track the fragments and cache a small range descriptor. Duplicate fragments are 
dropped and overlaps are cropped. Thus data will only occur once on the wire with ambiguities re¬ 
solving to the first occurrence. Unlike the fragment reassemble modifier, fragments are not 
buffered, they are passed as soon as they are received. The fragment crop reassembly mecha¬ 
nism does not yet work with NAT. 

fragment drop-ovl 

This option is similar to the fragment crop modifier except that all overlapping or duplicate frag¬ 
ments will be dropped, and all further corresponding fragments will be dropped as well. 

For example, 

scrub in on $ext_if all fragment reassemble 
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QUEUEING 

Packets can be assigned to queues for the purpose of bandwidth control. At least two declarations are re¬ 
quired to configure queues, and later any packet filtering rule can reference the defined queues by name. 
During the filtering component of pf .conf, the last referenced queue name is where any packets from 
pass rules will be queued, while for block rules it specifies where any resulting ICMP or TCP RST pack¬ 
ets should be queued. The scheduler defines the algorithm used to decide which packets get delayed, 
dropped, or sent out immediately. There are two schedulers currently supported. 

cbq Class Based Queueing. Queues attached to an interface build a tree, thus each queue can have fur¬ 
ther child queues. Each queue can have a priority and a bandwidth assigned. Priority 
mainly controls the time packets take to get sent out, while bandwidth has primarily effects on 
throughput. 

priq Priority Queueing. Queues are flat attached to the interface, thus, queues cannot have further child 
queues. Each queue has a unique priority assigned, ranging from 0 to 15. Packets in the 
queue with the highest priority are processed first. 

The interfaces on which queueing should be activated are declared using the alt q on declaration, altq 
on has the following keywords: 

<interface> 

Queueing is enabled on the named interface. 

<scheduler> 

Specifies which queueing scheduler to use. Currently supported values are cbq for Class Based 
Queueing and priq for Priority Queueing. 

bandwidth <bw> 

The maximum bitrate for all queues on an interface may be specified using the bandwidth 
keyword. The value can be specified as an absolute value or as a percentage of the interface band¬ 
width. When using an absolute value, the suffixes b, Kb , Mb , and Gb are used to represent bits, kilo¬ 
bits, megabits, and gigabits per second, respectively. The value must not exceed the interface band¬ 
width. If bandwidth is not specified, the interface bandwidth is used. 

qlimit <liwit> 

The maximum number of packets held in the queue. The default is 50. 

tbrsize <size> 

Adjusts the size, in bytes, of the token bucket regulator. If not specified, heuristics based on the inter¬ 
face bandwidth are used to determine the size. 

queue <list> 

Defines a list of subqueues to create on an interface. 

In the following example, the interface dcO should queue up to 5 Mbit/s in four second-level queues using 
Class Based Queueing. Those four queues will be shown in a later example. 

altq on dcO cbq bandwidth 5Mb queue { std, http, mail, ssh } 

Once interfaces are activated for queueing using the al tq directive, a sequence of queue directives may be 
defined. The name associated with a queue must match a queue defined in the altq directive (e.g. mail), 
or, for the cbq scheduler , in a parent queue declaration. The following keywords can be used: 

bandwidth <bw> 

Specifies the maximum bitrate to be processed by the queue. This value must not exceed the value of 
the parent queue and can be specified as an absolute value or a percentage of the parent queue’s 
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bandwidth. The prig scheduler does not support bandwidth specification. 

priority <level> 

Between queues a priority level can be set. For cjbg, the range is 0 to 7 and for prig, the range is 0 
to 15. The default for both is 1. Priq queues with a higher priority are always served first. Cbq 
queues with a higher priority are preferred in the case of overload. 

qlimit <limit> 

The maximum number of packets held in the queue. The default is 50. 

The scheduler can get additional parameters with <scheduler> ( <parameters> ). Parameters 
are as follows: 

default Packets not matched by another queue are assigned to this one. Exactly one default queue is 
required. 

red Enable RED (Random Early Detection) on this queue. RED drops packets with a probability 

proportional to the average queue length. 

rio Enables RIO on this queue. RIO is RED with IN/OUT, thus running RED two times more than 

RIO would achieve the same effect. RIO is currently not supported in the GENERIC kernel. 

ecn Enables ECN (Explicit Congestion Notification) on this queue. ECN implies RED. 

The cbq scheduler supports an additional option: 

borrow The queue can borrow bandwidth from the parent. 

Furthermore, with cbq, child queues can be specified as in an altq declaration, thus building a tree of 
queues using a part of their parent’s bandwidth. 

Packets can be assigned to queues based on filter rules by using the queue keyword. Normally only one 
queue is specified; when a second one is specified it will instead be used for packets which have a TOS of 
lowdelay and for TCP ACKs with no data payload. 

To continue the previous example, the examples below would specify the four referenced queues, plus a few 
child queues. Interactive ssh(l) sessions get priority over bulk transfers like scp(l) and sftp(l). The 
queues may then be referenced by filtering rules (see PACKET FILTERING below). 

queue std bandwidth 10% cbq(default) 

queue http bandwidth 60% priority 2 cbq(borrow red) \ 

{ employees, developers } 
queue developers bandwidth 75% cbq(borrow) 
queue employees bandwidth 15% 

queue mail bandwidth 10% priority 0 cbq(borrow ecn) 

queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk } 

queue ssh_interactive priority 7 

queue ssh_bulk priority 0 

block return out on dcO inet all queue std 

pass out on dcO inet proto tcp from $developerhosts to any port 80 \ 
keep state queue developers 

pass out on dcO inet proto tcp from $employeehosts to any port 80 \ 
keep state queue employees 

pass out on dcO inet proto tcp from any to any port 22 \ 
keep state queue(ssh_bulk, ssh_interactive) 
pass out on dcO inet proto tcp from any to any port 25 \ 
keep state queue mail 
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TRANSLATION 

Translation rules modify either the source or destination address of the packets associated with a stateful con¬ 
nection. A stateful connection is automatically created to track packets matching such a rule as long as they 
are not blocked by the filtering section of pf .conf. The translation engine modifies the specified address 
and/or port in the packet, recalculates IP, TCP and UDP checksums as necessary, and passes it to the packet 
filter for evaluation. Translation occurs before filtering. 

The state entry created permits pf (4) to keep track of the original address for traffic associated with that state 
and correctly direct return traffic for that connection. 

Various types of translation are possible with pf: 

binat 

A binat rule specifies a bidirectional mapping between an external IP netblock and an internal IP 
netblock. 

nat A nat rule specifies that IP addresses are to be changed as the packet traverses the given interface. 
This technique allows one or more IP addresses on the translating host to support network traffic for a 
larger range of machines on an "inside” network. Although in theory any IP address can be used on 
the inside, it is strongly recommended that one of the address ranges defined by RFC 1918 be used. 
These netblocks are: 

10.0.0.0 - 10.255.255.255 (all of net 10, i.e., 10/8) 

172.16.0.0 - 172.31.255.255 (i.e., 172.16/12) 

192.168.0.0 - 192.168.255.255 (i.e., 192.168/16) 

rdr The packet is redirected to another destination and possibly a different port, rdr rules can optionally 
specify port ranges instead of single ports, rdr ... port 2000:2999 -> ... port 4000 redirects ports 2000 
to 2999 (inclusive) to port 4000. rdr ... port 2000:2999 -> ... port 4000:* redirects port 2000 to 4000, 
2001 to 4001,..., 2999 to 4999. 

In addition to modifying the address, some translation rules may modify source or destination ports for 
tcp(4) or udp(4) connections; implicitly in the case of nat rules and explicitly in the case of rdr rules. 
Port numbers are never translated with a binat rule. 

For each packet processed by the translator, the translation rules are evaluated in sequential order, from first 
to last. The first matching rule decides what action is taken. 

The no option prefixed to a translation rule causes packets to remain untranslated, much in the same way as 
drop quick works in the packet filter (see below). 

If no rule matches the packet, the packet is passed to the filter unmodified. Translation occurs before the fil¬ 
ter rules are applied; therefore rules for redirected packets should specify the address and port after transla¬ 
tion. 

Translation rules apply only to packets that pass through the specified interface, and if no interface is speci¬ 
fied, translation is applied to packets on all interfaces. For instance, redirecting port 80 on an external inter¬ 
face to an internal web server will only work for connections originating from the outside. Connections to 
the address of the external interface from local hosts will not be redirected, since such packets do not actually 
pass through the external interface. Redirections cannot reflect packets back through the interface they arrive 
on, they can only be redirected to hosts connected to different interfaces or to the firewall itself. 

Note that redirecting external incoming connections to the loopback address, as in 

rdr on ne3 inet proto top to port 8025 -> 127.0.0.1 port 25 

will effectively allow an external host to connect to daemons bound solely to the loopback address, circum¬ 
venting the traditional blocking of such connections on a real interface. Unless this effect is desired, any of 


OpenBSD 3.3 


November 19, 2002 


8 



PF.CONF (5) 


OpenBSD Programmer's Manual 


PF.CONF (5) 


the local non-loopback addresses should be used as redirection target instead, which allows external connec¬ 
tions only to daemons bound to this address or not bound to any address. 

See TRANSLATION EXAMPLES below. 

PACKET FILTERING 

pf(4) has the ability to block and pass packets based on attributes of their layer 3 (see ip(4) and ip6(4)) 
and layer 4 (see icmp(4), icmp6(4), tcp(4), udp(4)) headers. In addition, packets may also be assigned to 
queues for the purpose of bandwidth control. 

For each packet processed by the packet filter, the filter rules are evaluated in sequential order, from first to 
last. The last matching rule decides what action is taken. 

The following actions can be used in the filter: 

block 

The packet is blocked. There are a number of ways in which a block rule can behave when block¬ 
ing a packet. The default behaviour is to drop packets silently, however this can be overridden or 
made explicit either globally, by setting the block-policy option, or on a per-rule basis with one 
of the following options: 

drop The packet is silently dropped. 

return-rst 

This applies only to tcp(4) packets, and issues a TCP RST which closes the connection. 

return-icmp 

return-icmp6 

This causes ICMP messages to be returned for packets which match the rule. By default this 
is an ICMP UNREACHABLE message, however this can be overridden by specifying a mes¬ 
sage as a code or number. 

return 

This causes a TCP RST to be returned for tcp(4) packets, an ICMP UNREACHABLE for 
UDP packets, and silently drops all other packets. 

pass The packet is passed. 

If no rule matches the packet, the default action is pass. 

To block everything by default and only pass packets that match explicit rules, one uses 
block all 
as the first filter rule. 

See FILTER EXAMPLES below. 

PARAMETERS 

The rule parameters specify the packets to which a rule applies. A packet always comes in on, or goes out 
through, one interface. Most parameters are optional. If a parameter is specified, the rule only applies to 
packets with matching attributes. Certain parameters can be expressed as lists, in which case pf ctl(8) gen¬ 
erates all needed rule combinations. 

in or out 

This rule applies to incoming or outgoing packets. If neither in nor out are specified, the rule will 
match packets in both directions. 

log In addition to the action specified, a log message is generated. All packets for that connection are 
logged, unless the keep state or modulate state options are specified, in which case only 
the packet that establishes the state is logged. (See keep state and modulate state below). 
The logged packets are sent to the pflog(4) interface. This interface is monitored by the 
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pflogd(8) logging daemon, which dumps the logged packets to the file /var/log/pflog in 
pcap(3) binary format. 

log-all 

Used with keep state or modulate state rules to force logging of all packets for a connec¬ 
tion. As with log, packets are logged to pf log(4). 

quick 

If a packet matches a rule which has the quick option set, this rule is considered the last matching 
rule, and evaluation of subsequent rules is skipped. 

on <interface> 

This rule applies only to packets coming in on, or going out through, this particular interface. 

<af> This rule applies only to packets of this address family. Supported values are inet and inet 6 . 
proto <protocol> 

This rule applies only to packets of this protocol. Common protocols are icmp(4), icmp6(4), 
tcp(4), and udp(4). For a list of all the protocol name to number mappings used by pfctl(8), see 
the file /etc/protocols. 

from <scurce> port <source> to <dest> port <dest> 

This rule applies only to packets with the specified source and destination addresses and ports. 

Addresses can be specified in CIDR notation (matching netblocks), as symbolic host names or inter¬ 
face names, or as any of the following keywords: 

any Any address. 

no-route Any address which is not currently routable. 

<table> Any address that matches the given table. 

Interface names can have modifiers appended: 

; network Translates to the network(s) attached to the interface. 
broadcast Translates to the interface’s broadcast address(es). 

Host name resolution and interface to address translation are done at ruleset load-time. When the ad¬ 
dress of an interface (or host name) changes (under DHCP or PPP. for instance), the ruleset must be 
reloaded for the change to be reflected in the kernel. Surrounding the interface name in parentheses 
changes this behaviour. When the interface name is surrounded by parentheses, the rule is automati¬ 
cally updated whenever the interface changes its address. The ruleset does not need to be reloaded. 
This is especially useful with nat. 

Ports can be specified either by number or by name. For example, port 80 can be specified as www. 
For a list of all port name to number mappings used by pfcti(8), see the file /etc/services. 

Ports and ranges of ports are specified by using these operators: 

= (equal) 

!= (unequal) 

< (less than) 

<= (less than or equal) 

> (greater than) 

>= (greater than or equal) 

>< (range) 

<> (except range) 

>< and <> are binary operators (they take two arguments), and the range does not include the limits. 
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For instance: 

port 2000 >< 2004 

means ‘all ports > 2000 and < 2004’, hence ports 2001,2002 and 2003. 

port 2000 <> 2004 

means ‘all ports < 2000 or > 2004’, hence ports 1-1999 and 2005-65535. 

The host and port specifications are optional, as in the following examples: 

pass in all 

pass in from any to any 

pass in proto top from any port <= 1024 to any 
pass in proto top from any to any port 25 

pass in proto top from 10.0.0.0/8 port > 1024 \ 

to ! 10.1.2.3 port != ssh 

all This is equivalent to "from any to any". 

group <group> 

Similar to user , this rule only applies to packets of sockets owned by the specified group. 

user <user> 

This rule only applies to packets of sockets owned by the specified user. For outgoing connections 
initiated from the firewall, this is the user that opened the connection. For incoming connections to 
the firewall itself, this is the user that listens on the destination port. For forwarded connections, 
where the firewall is not a connection endpoint, the user and group are unknown. 

All packets, both outgoing and incoming, of one connection are associated with the same user and 

group. Only TCP and UDP packets can be associated with users; for other protocols these parameters 

are ignored. 

User and group refer to the effective (as opposed to the real) IDs, in case the socket is created by a se- 

tuid/setgid process. User and group IDs are stored when a socket is created; when a process creates a 

listening socket as root (for instance, by binding to a privileged port) and subsequently changes to an¬ 
other user ID (to drop privileges), the credentials will remain root. 

User and group IDs can be specified as either numbers or names. The syntax is similar to the one for 
ports. The value unknown matches packets of forwarded connections, unknown can only be used 
with the operators = and !=. Other constructs like user >= unknown are invalid. Forwarded 
packets with unknown user and group ID match only rules that explicitly compare against unknown 
with the operators = or !=. For instance user >= 0 does not match forwarded packets. The fol¬ 
lowing example allows only selected users to open outgoing connections: 

block out proto { tcp, udp } all 

pass out proto { tcp, udp } all \ 

user { < 1000, dhartmei } keep state 

flags <a>/<b> I /<b> 

This rule only applies to TCP packets that have the flags <a> set out of set <b>. Flags not specified 
in <b> are ignored. The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and 
C(W)R. 

flags S/S 

Flag SYN is set. The other flags are ignored. 

flags S/SA 

Out of SYN and ACK, exactly SYN may be set. SYN, SYN+PSH and SYN+RST 
match, but SYN+ACK, ACK and ACK+RST do not. This is more restrictive than the 
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previous example. 

flags /SFRA 

If the first set is not specified, it defaults to none. All of SYN, FIN, RST and ACK must 
be unset. 

icmp-type <type> code <code> 
icmp6-type <type> code <code> 

This rule only applies to ICMP or ICMPv6 packets with the specified type and code. This parameter 
is only valid for rules that cover protocols ICMP or ICMP6. The protocol and the ICMP type indica¬ 
tor (icmp-type or icmp6-type) must match. 

allow-opts 

By default, packets which contain IP options are blocked. When allow-opts is specified for a 
pass rule, packets that pass the filter based on that rule (last matching) do so even if they contain IP 
options. For packets that match state, the rule that initially created the state is used. The implicit 
pass rule that is used when a packet does not match any rules does not allow IP options. 

label <string> 

Adds a label (name) to the rule, which can be used to identify the rule. For instance, pfctl -s labels 
shows per-rule statistics for rules that have labels. 

The following macros can be used in labels: 

$if The interface. 

$srcaddr The source IP address. 

$dstaddr The destination IP address. 

$sreport The source port specification. 

$dstport The destination port specification. 

$proto The protocol name. 

$nr The rule number. 

For example: 

ips = "{ 1.2.3.4, 1.2.3.5 }" 

pass in proto top from any to $ips \ 

port > 1023 label "$dstaddr:$dstport" 

expands to 

pass in inet proto tep from any to 1.2.3.4 \ 
port > 1023 label "1.2.3.4:>1023" 
pass in inet proto tep from any to 1.2.3.5 \ 
port > 1023 label "1.2.3.5:>1023" 

The macro expansion for the label directive occurs only at configuration file parse time, not during 
runtime. 

queue <queue> I (<queue>, <queue>) 

Packets matching this rule will be assigned to the specified queue. If two queues are given, packets 
which have a tos of lowdelay and TCP ACKs with no data payload will be assigned to the second one. 
See QUEUE RULES for setup details. 

For example: 

pass in proto tep to port 25 queue mail 

pass in proto tep to port 22 queue(ssh_bulk, ssh_prio) 
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ROUTING 

If a packet matches a rule with a route option set, the packet filter will route the packet according to the type 
of route option. When such a rule creates state, the route option is also applied to all packets matching the 
same connection. 

fastroute 

The fastroute option does a normal route lookup to find the next hop for the packet. 

route-to 

The route-to option routes the packet to the specified interface with an optional address for the 
next hop. When a route-to rule creates state, only packets that pass in the same direction as the 
filter rule specifies will be routed in this way. Packets passing in the opposite direction (replies) are 
not affected and are routed normally. 

reply-to 

The reply-to option is similar to route-to , but routes packets that pass in the opposite direction 
(replies) to the specified interface. Opposite direction is only defined in the context of a state entry, 
and route-to is useful only in rules that create state. It can be used on systems with multiple ex¬ 
ternal connections to route all outgoing packets of a connection through the interface the incoming 
connection arrived through (symmetric routing enforcement). 

dup-to 

The dup-to option creates a duplicate of the packet and routes it like route-to . The original 
packet gets routed as it normally would. 

POOL OPTIONS 

For nat and rdr rules, (as well as for the route-to , reply-to and dup-to rule options) for which 
there is a single redirection address which has a subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more 
than one IP address), a variety of different methods for assigning this address can be used: 

bitmask 

The bitmask option applies the network portion of the redirection address to the address to be mod¬ 
ified (source with nat, destination with rdr). 

random 

The random option selects an address at random within the defined block of addresses. 

source-hash 

The source-hash option uses a hash of the source address to determine the redirection address, 
ensuring that the redirection address is always the same for a given source. An optional key can be 
specified after this keyword either in hex or as a string; by default pfctl(8) randomly generates a 
key for source-hash every time the ruleset is reloaded. 

round-robin 

The round-robin option loops through the redirection address(es). 

When more than one redirection address is specified, round-robin is the only permitted pool type. 

static-port 

With nat rules, the static-port option prevents pf(4) from modifying the source port on tcp 
and udp packets. 

STATEFUL INSPECTION 

pf (4) is a stateful packet filter, which means it can track the state of a connection. Instead of passing all traf¬ 
fic to port 25, for instance, it is possible to pass only the initial packet, and then begin to keep state. Subse¬ 
quent traffic will flow because the filter is aware of the connection. 
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If a packet matches a pass . . . keep state rule, the filter creates a state for this connection and auto¬ 
matically lets pass all subsequent packets of that connection. 

Before any rules are evaluated, the filter checks whether the packet matches any state. If it does, the packet 
is passed without evaluation of any rules. 

States are removed after the connection is closed or has timed out. 

This has several advantages. Comparing a packet to a state involves checking its sequence numbers. If the 
sequence numbers are outside the narrow windows of expected values, the packet is dropped. This prevents 
spoofing attacks, such as when an attacker sends packets with a fake source address/port but does not know 
the connection’s sequence numbers. 

Also, looking up states is usually faster than evaluating rules. If there are 50 rules, all of them are evaluated 
sequentially in O(n). Even with 50000 states, only 16 comparisons are needed to match a state, since states 
are stored in a binary search tree that allows searches in 0(log2 n). 

For instance: 

block all 

pass out proto tcp from any to any flags S/SA keep state 

pass in proto tcp from any to any port 25 flags S/SA keep state 

This ruleset blocks everything by default. Only outgoing connections and incoming connections to port 25 
are allowed. The initial packet of each connection has the SYN flag set, will be passed and creates state. All 
further packets of these connections are passed if they match a state. 

Specifying flags S/SA restricts state creation to the initial SYN packet of the TCP handshake. One can 
also be less restrictive, and allow state creation from intermediate (non-SYN) packets. This will cause 
pf (4) to synchronize to existing connections, for instance if one flushes the state table. 

For UDP, which is stateless by nature, keep state will create state as well. UDP packets are matched to 
states using only host addresses and ports. 

ICMP messages fall into two categories: ICMP error messages, which always refer to a TCP or UDP packet, 
are matched against the referred to connection. If one keeps state on a TCP connection, and an ICMP source 
quench message referring to this TCP connection arrives, it will be matched to the right state and get passed. 

For ICMP queries, keep state creates an ICMP state, and pf(4) knows how to match ICMP replies to 
states. For example, 

pass out inet proto icmp all lcmp-type echoreq keep state 

allows echo requests (such as those created by ping(8)) out, creates state, and matches incoming echo 
replies correctly to states. 

Note: na t. binat and rdr rules implicitly create state for connections. 

STATE MODULATION 

Much of the security derived from TCP is attributable to how well the initial sequence numbers (ISNs) are 
chosen. Some popular stack implementations choose very > poor ISNs and thus are normally susceptible to 
ISN prediction exploits. By applying a modulate state rule to a TCP connection, pf(4) will create a 
high quality random sequence number for each connection endpoint. 

The modulate state directive implicitly keeps state on the rule and is only applicable to TCP connec¬ 
tions. 

For instance: 
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block all 

pass out proto tcp from any to any modulate state 

pass in proto tcp from any to any port 25 flags S/SA modulate state 

There are two caveats associated with state modulation: A modulate state rule can not be applied to a 
pre-existing but unmodulated connection. Such an application would desynchronize TCP’s strict sequencing 
between the two endpoints. Instead, pf(4) will treat the modulate state modifier as a keep state 
modifier and the pre-existing connection will be inferred without the protection conferred by modulation. 

The other caveat affects currently modulated states when the state table is lost (firewall reboot, flushing the 
state table, etc...), pf(4) will not be able to infer a connection again after the state table flushes the connec¬ 
tion’s modulator. When the state is lost, the connection may be left dangling until the respective endpoints 
time out the connection. It is possible on a fast local network for the endpoints to start an ACK storm while 
trying to resynchronize after the loss of the modulator. Using a flags S/SA modifier on modulate 
state rules between fast networks is suggested to prevent ACK storms. 

STATEFUL TRACKING OPTIONS 

Both keep state and modulate state support the following options: 

max <number> 

Limits the number of concurrent states the rule may create. When this limit is reached, further pack¬ 
ets matching the rule that would create state are dropped, until existing states time out. 

<timeout> <seconds> 

Changes the timeout values used for states created by this rule. For a list of all valid timeout names, 
see OPTIONS above. 

Multiple options can be specified, separated by commas: 

pass in proto tcp from any to any \ 

port www flags S/SA keep state \ 

(max 100, tcp.established 60, tcp.closing 5) 

BLOCKING SPOOFED TRAFFIC 

"Spoofing” is the faking of IP addresses, typically for malicious purposes. The antispoof directive ex¬ 
pands to a set of filter rules which will block all traffic with a source IP from the network(s) directly connect¬ 
ed to the specified interface(s) from entering the system through any other interface. 

For example, the line 

antispoof for loO 

expands to 

block drop in on ! loO inet from 127.0.0.1/8 to any 

block drop in on ! loO inet6 from ::1 to any 

For non-loopback interfaces, there are additional rules to block incoming packets with a source IP address 
identical to the interface’s IP(s). For example, assuming the interface wiO had an IP address of 10.0.0.1 and a 
netmask of 255.255.255.0, the line 

antispoof for wiO inet 

expands to 

block drop in on ! wiO inet from 10.0.0.0/24 to any 

block drop in inet from 10.0.0.1 to any 
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Caveat: Rules created by the antispoof directive interfere with packets sent over loopback interfaces to 
local addresses. One should pass these explicitly. 

FRAGMENT HANDLING 

The size of IP datagrams (packets) can be significantly larger than the the maximum transmission unit 
(MTU) of the network. In cases when it is necessary or more efficient to send such large packets, the large 
packet will be fragmented into many smaller packets that will each fit onto the wire. Unfortunately for a fire¬ 
walling device, only the first logical fragment will contain the necessary header information for the subproto¬ 
col that allows pf (4) to filter on things such as TCP ports or to perform NAT. 

Besides the use of scrub rules as described in TRAFFIC NORMALIZATION above, there are three options 
for handling fragments in the packet filter. 

One alternative is to filter individual fragments with filter rules. If no scrub rule applies to a fragment, it is 
passed to the filter. Filter rules with matching IP header parameters decide whether the fragment is passed or 
blocked, in the same way as complete packets are filtered. Without reassembly, fragments can only be fil¬ 
tered based on IP header fields (source/destination address, protocol), since subprotocol header fields are not 
available (TCP/UDP port numbers, ICMP code/type). The fragment option can be used to restrict filter 
rules to apply only to fragments, but not complete packets. Filter rules without the fragment option still 
apply to fragments, if they only specify IP header fields. For instance, the rule 

pass in proto tcp from any to any port 80 

never applies to a fragment, even if the fragment is part of a TCP packet with destination port 80, because 
without reassembly this information is not available for each fragment. This also means that fragments can¬ 
not create new- or match existing state table entries, which makes stateful filtering and address translation 
(NAT, redirection) for fragments impossible. 

It's also possible to reassemble only certain fragments by specifying source or destination addresses or proto¬ 
cols as parameters in scrub rules. 

In most cases, the benefits of reassembly outweigh the additional memory cost, and it’s recommended to use 
scrub rules to reassemble all fragments via the fragment reassemble modifier. 

The memory allocated for fragment caching can be limited using pfctl(8). Once this limit is reached, frag¬ 
ments that would have to be cached are dropped until other entries time out. The timeout value can also be 
adjusted. 

Currently, only IPv4 fragments are supported and IPv6 fragments are blocked unconditionally. 

ANCHORS AND NAMED RULESETS 

Besides the main ruleset, pfctl(8) can load named rulesets into anchor attachment points. An anchor 
contains a list of named rulesets. An anchor has a name which specifies where pfctl(8) can be used to 
attach sub-rulesets. A named ruleset contains filter and translation rules, like the main ruleset. The main 
ruleset can reference anchor attachment points using the following kinds of rules: 

nat-anchor <name> 

Evaluates the nat rules of all named rulesets in the specified anchor . 
rdr-anchor <name> 

Evaluates the rdr rules of all named rulesets in the specified anchor, 
binat-anchor <name> 

Evaluates the binat rules of all named rulesets in the specified anchor, 
anchor <name> 

Evaluates the filter rules of all named rulesets in the specified anchor. 
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When evaluation of the main ruleset reaches an anchor rule, pf(4) will proceed to evaluate all rules speci¬ 
fied in the named rulesets attached to that anchor . 

Matching filter rules in named rulesets with the quick option and matching translation rules are final and 
abort the evaluation of both the rules in the anchor and the main ruleset. 

Only the main ruleset can contain anchor rules. 

When an anchor contains more than one named ruleset, they are evaluated in the alphabetical order of their 
names. 

Rules may contain anchor attachment points which do not contain any rules when the main ruleset is load¬ 
ed, and later such named rulesets can be manipulated through pfctl(8) without reloading the main ruleset. 
For example, 

ext_if = "kueO" 
block on $ext_if all 
anchor spam 

pass out on $ext_if all keep state 
pass in on $ext_if proto tcp from any \ 
to $ext_if port smtp keep state 

blocks all packets on the external interface by default, then evaluates all rulesets in the anchor named 
"spam", and finally passes all outgoing connections and incoming connections to port 25. 

# echo "block in quick from 1.2.3.4 to any" | \ 

pfctl -a spamimanual -f - 

loads a single ruleset containing a single rule into the anchor , which blocks all packets from a specific ad¬ 
dress. 

Optionally, anchor rules can specify the parameter’s direction, interface, address family, protocol and 
source/destination address/port using the same syntax as filter rules. When parameters are used, the anchor 
rule is only evaluated for matching packets. This allows conditional evaluation of named rulesets, like: 

block on $ext_if all 

anchor spam proto tcp from any to any port smtp 
pass out on $ext_if all keep state 

pass in on $ext_if proto tcp from any to $ext_if port smtp keep state 

The rules inside anchor spam are only evaluated for tcp packets with destination port 25. Hence, 

# echo "block in quick from 1.2.3.4 to any" | \ 

pfctl -a spamimanual -f - 

will only block connections from 1.2.3.4 to port 25. 

TRANSLATION EXAMPLES 

This example maps incoming requests on port 80 to port 8080, on which a daemon is running (because, for 
example, it is not run as root, and therefore lacks permission to bind to port 80). 

# map daemon on 8080 to appear to be on 80 

rdr on ne3 proto tcp from any to any port 80 -> 127.0.0.1 port 8080 

In the example below, vlanl2 is configured as 192.168.168.1; the machine translates all packets coming from 
192.168.168.0/24 to 204.92.77.111 when they are going out any interface except vlanl2. This has the net ef¬ 
fect of making traffic from the 192.168.168.0/24 network appear as though it is the Internet routable address 
204.92.77.111 to nodes behind any interface on the router except for the nodes on vlanl2. (Thus, 
192.168.168.1 can talk to the 192.168.168.0/24 nodes.) 
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nat on ! vlanl2 from 192.168.168.0/24 to any -> 204.92.77.111 

In the example below, fxpl is the outside interface; the machine sits between a fake internal 144.19.74.* net¬ 
work, and a routable external IP of 204.92.77.100. The no nat rule excludes protocol AH from being 
translated. 

# NO NAT 

no nat on fxpl proto ah from 144.19.74.0/24 to any 
nat on fxpl from 144.19.74.0/24 to any -> 204.92.77.100 

In the example below, fxpO is the internal interface. Packets bound for one specific server, as well as those 
generated by the sysadmins are not proxied; all other connections are. 

# NO RDR 

no rdr on fxpO proto { top, udp } from any to Sserver port 80 

no rdr on fxpO proto { top, udp } from $sysadmins to any port 80 

rdr on fxpO proto { top, udp } from any to any port 80 -> 127.0.0.1 port 80 

This longer example uses both a NAT and a redirection. Interface kueO is the outside interface, and its exter¬ 
nal address is 157.161.48.183. Interface fxpO is the inside interface, and we are running ftp-proxy(8), 
listening for outbound ftp sessions captured to port 8081. 

# NAT 

# translate outgoing packets' source addresses (any protocol) 

# in this case, any address but the gateway's external address is mapped 
nat on kueO inet from ! (kueO) to any -> (kueO) 

# NAT PROXYING 

# map outgoing packets' source port to an assigned proxy port instead of 

# an arbitrary port 

# in this case, proxy outgoing isakmp with port 500 on the gateway 
nat on kueO inet proto udp from any port = isakmp to any -> (kueO) \ 

port 500 


# BINAT 

# translate outgoing packets' source address (any protocol) 

# translate incoming packets' destination address to an internal machine 

# (bidirectional) 

binat on kueO from 10.1.2.150 to any -> (kueO) 


# RDR 

# translate incoming packets' destination addresses 

# as an example, redirect a TCP and UDP port to an internal machine 
rdr on kueO inet proto tcp from any to (kueO) port 8080 -> 10.1.2.151 \ 

port 22 

rdr on kueO inet proto udp from any to (kueO) port 8080 -> 10.1.2.151 \ 
port 53 


# RDR 

# translate outgoing ftp control connections to send them to localhost 

# for proxying with ftp-proxy(8) running on port 8081 

rdr on fxpO proto tcp from any to any port 21 -> 127.0.0.1 port 8081 

In this example, a NAT gateway is set up to translate internal addresses 
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using a pool of public addresses (192.0.2.16/28) and to redirect 
incoming web server connections to a group of web servers on the internal 
network. 

Interface fxpO is the external interface. 

# NAT LOAD BALANCE 

# translate outgoing packets' source addresses using an address pool. A 

# given source address is always translated to the same pool address by 

# using the source-hash keyword. 

nat on fxpO inet from any to any -> 192.0.2.16/28 source-hash 

# RDR ROUND ROBIN 

# translate incoming web server connections to a group of web servers on 

# the internal network 

rdr on fxpO proto tcp from any to any port 80 \ 

-> { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin 

FILTER EXAMPLES 

# The external interface is kueO 

# (157.161.48.183, the only routable address) 

# and the private network is 10.0.0.0/8, for which we are doing NAT. 

# use a macro for the interface name, so it can be changed easily 
ext_if = "kueO" 

# normalize all incoming traffic 

scrub in on $ext_if all fragment reassemble 

# block and log everything by default 
block return log on $ext_if all 

# block anything coming from source we have no back routes for 
block in from no-route to any 

# block and log outgoing packets that do not have our address as source, 

# they are either spoofed or something is misconfigured (NAT disabled, 

# for instance), we want to be nice and do not send out garbage, 
block out log quick on $ext_if from ! 157.161.48.183 to any 

# silently drop broadcasts (cable modem noise) 
block in quick on $ext_if from any to 255.255.255.255 

# block and log incoming packets from reserved address space and invalid 

# addresses, they are either spoofed or misconfigured, we cannot reply to 

# them anyway (hence, no return-rst). 

block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \ 
192.168.0.0/16, 255.255.255.255/32 ) to any 


# ICMP 
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# pass out/in certain ICMP queries and keep state (ping) 

# state matching is done on host addresses and ICMP id (not type/code), 

# so replies (like 0/0 for 8/0) will match queries 

# ICMP error messages (which always refer to a TCP/UDP packet) are 

# handled by the TCP/UDP states 

pass on $ext_if inet proto icmp all icmp-type 8 code 0 keep state 

# UDP 

# pass out all UDP connections and keep state 
pass out on $ext_if proto udp all keep state 

# pass in certain UDP connections and keep state (DNS) 

pass in on $ext_if proto udp from any to any port domain keep state 

# TCP 

# pass out all TCP connections and modulate state 
pass out on $ext_if proto tcp all modulate state 

# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT) 
pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \ 

auth } flags S/SA keep state 

# pass in data mode connections for ftp-proxy running on this host. 

# (see ftp-proxy(8) for details) 

pass in on $ext_if proto tcp from any to 157.161.48.183 port >= 49152 \ 
flags S/SA keep state 


GRAMMAR 

Syntax for pf. conf in BNF: 

line = ( option | pf-rule | nat-rule | binat-rule | rdr-rule 

I antispoof-rule I altq-rule | queue-rule ) 

option = set ( [ timeout ( timeout I { timeout-list } ) ] I 

[ optimization [ default | normal 
I high-latency | satellite 
I aggressive I conservative ] ] 

[ limit limit-list ] I 

[ loginterface ( interface-name | none ) ] | 

[ block-policy ( drop | return ) ] | 

[ require-order ( yes | no ) ] ) 

pf-rule = action [ ( in | out ) ] 

[ log I log-all ] [ quick ] 

[ on ifspec ] [ route ] [ af ] [ protospec ] 

hosts [ filteropt-list ] 


filteropt-list = filteropt-list filteropt | filteropt 

filteropt = user | group | flags | icmp-type | icmp6-type I tos | 

( keep I modulate ) state [ ( state-opts ) ] | 
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nat-rule 


binat-rule 


rdr-rule 


antispoof-rule 


table-rule 

tableopts-list 

tableopts 

tableaddr-list 

tableaddr-spec 

tableaddr 


altq-rule 

queue-rule 

queueopts-list 

queueopts 


schedulers 

action 

return 


icmpcode 

icmp6code 

ifspec 

interface-list 

route 


fragment | no-df | min-ttl number | max-mss number | 
random-id | fragmentation | allow-opts I 

label string | queue ( string | ( string [ [ , ] string ] ) ) 

[ no ] nat [ on ifspec ] [ af ] [ protospec ] 

hosts [ -> ( redirhost I { redirhost-list } ) 

[ portspec ] ] [ pooltype ] [ static-port ] 

[ no ] binat [ on interface-name ] [ af ] 

[ proto ( proto-name | proto-number ) ] 

from address [ / mask-bits ] to ipspec 
[ -> address [ / mask-bits ] ] 

[ no ] rdr [ on ifspec ] [ af ] [ protospec ] 

hosts [ -> ( redirhost | { redirhost-list } ) 

[ portspec ] ] [ pooltype ] 

antispoof [ log ] [ quick ] 

for ( interface-name | { interface-list } ) [ af ] 

table < tablename > [ tableopts-list ] 
tableopts-list tableopts | tableopts 

persist | const I file "filename" | { [ tableaddr-list ] } 

tableaddr-list [ , ] tableaddr-spec I tableaddr-spec 

[ ! ] tableaddr [ / mask-bits ] 

hostname | ipv4-dotted-quad | ipv6-coloned-hex | 
interface-name | self 

altq on interface-name queueopts-list 
queue queue-list 

queue string queueopts-list queue-list 

queueopts-list queueopts | queueopts 
[ bandwidth number ( b | Kb | Mb | Gb | %) ] | 

[ qlimit number ] | [ tbrsize number ] | 

[ priority number ] | [ schedulers ] | 

[ qlimit number ] 

( cbq-def I priq-def ) 

pass | block [ return ] | scrub 

drop | return | return-rst [ ( tti number ) ] 

I return-icmp [ ( icmpcode [, icmp6code ] ) ] 

I return-icmp6 [ ( icmp6code ) ] 

( icmp-code-name I icmp-code-number ) 

( icmp6-code-name | icmp6-code-number ) 

( [ ! ] interface-name ) | { interface-list } 

[ ! ] interface-name [ [ , ] interface-list ] 

fastroute I 

( route-to | reply-to | dup-to ) 

( routehost ! { routehost-list } ) 

[ pooltype ] 
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af 

protospec 

proto-list 

hosts 


ipspec 

host 

redirhost 

routehost 

address 

host-list 

redirhost-list 

routehost-list 

port 

portspec 

user 

group 

unary-op 

binary-op 

op-list 

flags 

flag-set 

icmp-type 
icmp6-type 
icmp-type-code 

icmp-list 

tos 


state-opts 

state-opt 

fragmentation 

timeout-list 

timeout 


inet | inet6 

proto ( proto-name | proto-number | 

{ proto-list } ) 

( proto-name | proto-number ) [ [ , ] proto-list ] 

all | 

from ( any | no-route | self I host ! 

{ host-list } ) [ port ] 

to ( any | no-route | self I host I 

{ host-list } ) [ port ] 

any | host I { host-list } 

[ ! ] ( address [ / mask-bits ] | < table > ) 

address [ / mask-bits ] 

( interface-name [ address [ / mask-bits ] ] ) 

( interface-name | ( interface-name ) | host-name 

| ipv4-dotted-quad | ipv6-coloned-hex ) 

host [ [ , ] host-list ] 

redirhost [ [,] redirhost-list ] 

routehost [ [,] routehost-list ] 

port ( unary-op I binary-op | { op-list } ) 

port ( number | name ) [ : ( * I number | name ) ] 

user ( unary-op I binary-op | { op-list } ) 

group ( unary-op | binary-op I { op-list } ) 

[ = I != I < I <= I > I >= ] 

( name I number ) 
number ( <> | >< | : ) number 

( unary-op | binary-op ) [ [ , ] op-list ] 

flags ( flag-set / flag-set | / flag-set ) 
[Fj[S][R][P][A][U][E][W] 

icmp-type ( icmp-type-code | { icmp-list } ) 

icmp6-type ( icmp-type-code | { icmp-list } ) 

( icmp-type-name I icmp-type-number ) 

[ code ( icmp-code-name I icmp-code-number ) ] 

icmp-type-code [ [ , ] icmp-list ] 

tos ( lowdelay I throughput I reliability I 
[ Ox ] number ) 

state-opt [ [ , ] state-opts ] 

( max number ) I ( timeout seconds ) 

[ fragment reassemble I fragment crop 
I fragment drop-ovl ] 

timeout [ [ , ] timeout-list ] 

( tcp.first I tcp.opening | tcp.established 
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| tcp.closing | tcp.finwait I tcp.closed 
| udp.first | udp.single I udp.multiple 
| icmp.first I icmp.error 

I other.first I other.single I other.multiple ) 
seconds 

seconds = number 


limit-list = limit-item [ [ , ] limit-list ] 

limit-item = ( states | frags ) number 


pooltype = ( bitmask | random 

| source-hash [ ( hex-key I string-key ) ] 

I round-robin ) 


subqueue 

queue-list 

cbq-def 

priq-def 

cbq-opt 

priq-opt 


= string I { queue-list } 

= string [ [ , ] string ] 

= cbq [ ( cbq-opt [ [ , ] cbq-opt ] ) ] 

= priq [ ( priq-opt [ [ , ] priq-opt ] ) ] 

= ( default | borrow | red I ecn | rio ) 

= ( default | red | ecn | rio ) 


FILES 

/etc/hosts Host name database. 

/etc/pf . conf Default location of the ruleset file, 
/etc/protocols Protocol name database, 
/etc/services Service name database. 

/usr/share/pf Example rulesets. 


SEE ALSO 

icmp(4), icmp6(4), ip(4), ip6(4), pf(4), tcp(4), udp(4), hosts(5), protocols(5), services(5), 
ftp-proxy(8), pfctl(8), pf logd(8) 


HISTORY 

The pf. conf file format first appeared in OpenBSD 3.0. 


COPYRIGHT 

Copyright (c) 2002, Daniel Hartmeier 
All rights reserved. 

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met: 

- Redistributions of source code must retain the above copyright 
notice, this list of conditions and the following disclaimer. 

- Redistributions in binary form must reproduce the above 
copyright notice, this list of conditions and the following 
disclaimer in the documentation and/or other materials provided 
with the distribution. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
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LIMITED TO. THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT. 
INCIDENTAL. SPECIAL. EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING. 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 

LOSS OF USE, DATA. OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY. WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE. 
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NAME 

authpf - authenticating gateway user shell 

SYNOPSIS 

authpf 

DESCRIPTION 

authpf is a user shell for authenticating gateways. It is used to change pf(4) rules when a user authenti¬ 
cates and starts a session with sshd(8) and to undo these changes when the user's session exits. It is de¬ 
signed for changing filter and translation rules for an individual source IP address as long as a user maintains 
an active ssh(l) session. Typical use would be for a gateway that authenticates users before allowing them 
Internet use, or a gateway that allows different users into different places, authpf logs the successful start 
and end of a session to syslogd(8). This, combined with properly set up filter rules and secure switches, 
can be used to ensure users are held accountable for their network traffic. 

authpf can add filter and translation rules using the syntax described in pf .conf (5). authpf requires 
that the pf (4) system be enabled before use. 

authpf is meant to be used with users who can connect via ssh(l) only. On startup, authpf retrieves the 
client’s connecting IP address via the SSH_CLIENT environment variable and, after performing additional 
access checks, reads a template file to determine what filter and translation rules (if any) to add. On session 
exit the same rules that were added at startup are removed. 

Each authpf process stores its rules in a separate ruleset inside a pf(4) anchor shared by all authpf 
processes. By default, the anchor name "authpf is used, and the ruleset names equal the PIDs of the au¬ 
thpf processes. The following rules need to be added to the main ruleset /etc/pf. conf in order to 
cause evaluation of any authpf rules: 

nat-anchor authpf 
rdr-anchor authpf 
binat-anchor authpf 
anchor authpf 

FILTER AND TRANSLATION RULES 

Filter and translation rules for authpf use the same format described in pf . conf (5). The only difference 
is that these rules may (and probably should) use the macro userjp , which is assigned the connecting IP ad¬ 
dress whenever authpf is run. Additionally, the macro userjd is assigned the user name. 

Filter and nat rules will first be searched for in /etc/authpf/users/$USER/ and then in 
/etc/authpf /. Per-user rules from the /etc/authpf/users/$USER/ directory are intended to be 
used when non-default rules are needed on an individual user basis. It is important to ensure that a user can 
not write or change these configuration files. 

Filter and translation rules are loaded from the file /etc/authpf/users/$USER/authpf. rules. If 
this file does not exist the file /etc/authpf /authpf . rules is used. The authpf . rules file must 
exist in one of the above locations for authpf to run. 

Translation rules are also loaded from this file. The use of translation rules in an authpf .rules file is op¬ 
tional. 

CONFIGURATION 

Options are controlled by the /etc/authpf/authpf . conf file. If the file is empty or does not exist, 
defaults are used for all configuration options. The file consists of pairs of the form name=value, one per 
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line. Currently, the allowed values are as follows: 
anchor=name 

Use the specified anchor name instead of "authpf'. 

USER MESSAGES 

On successful invocation, authpf displays a message telling the user he or she has been authenticated. It 
will additionally display the contents of the file / etc/authpf/ authpf . message if the file exists and is 
readable. 

There exist two methods for providing additional granularity to the control offered by authpf - it is possi¬ 
ble to set the gateway to explicitly allow users who have authenticated to ssh(l) and deny access to only a 
few troublesome individuals. This is done by creating a file with the banned user's login name as the file¬ 
name in /etc/authpf/banned/. The contents of this file will be displayed to a banned user, thus pro¬ 
viding a method for informing the user that they have been banned, and where they can go and how to get 
there if they want to have their service restored. This is the default behaviour. 

It is also possible to configure authpf to only allow specific users access. This is done by listing their login 
names, one per line, in /etc/authpf/authpf. allow. If is found on a line, then all usernames 
match. If authpf is unable to verify the user's permission to use the gateway, it will print a brief message 
and die. It should be noted that a ban takes precedence over an allow. 

On failure, messages will be logged to syslogd(8) for the system administrator. The user does not see 
these, but will be told the system is unavailable due to technical difficulties. The contents of the file 
/etc/authpf/authpf .problem will also be displayed if the file exists and is readable. 

CONFIGURATION ISSUES 

authpf maintains the changed filter rules as long as the user maintains an active session. It is important to 
remember however, that the existence of this session means the user is authenticated. Because of this, it is 
important to configure sshd(8) to ensure the security of the session, and to ensure that the network through 
which users connect is secure. sshd(8) should be configured to use the Client Alive Interval and 
ClientAliveCountMax parameters to ensure that a ssh session is terminated quickly if it becomes unre¬ 
sponsive, or if arp or address spoofing is used to hijack the session. Note that TCP keepalives are not suffi¬ 
cient for this, since they are not secure. 

authpf will remove statetable entries that were created during a user’s session. This ensures that there will 
be no unauthenticated traffic allowed to pass after the controlling ssh(l) session has been closed. 

authpf is designed for gateway machines which typically do not have regular (non-administrative) users 
using the machine. An administrator must remember that authpf can be used to modify the filter rules 
through the environment in which it is run, and as such could be used to modify the filter rules (based on the 
contents of the configuration files) by regular users. In the case where a machine has regular users using it, 
as well as users with authpf as their shell, the regular users should be prevented from running authpf by 
using the /etc/authpf/authpf . allow or /etc/authpf/banned/ facilities. 

authpf modifies the packet filter and address translation rules, and because of this it needs to be configured 
carefully, authpf will not run and will exit silently if the /etc/authpf/authpf. conf file does not 
exist. After considering the effect authpf may have on the main packet filter rules, the system administra¬ 
tor may enable authpf by creating an appropriate /etc/authpf/authpf . conf file. 

EXAMPLES 

Control Files - To illustrate the user-specific access control mechanisms, let us consider a typical user named 
bob. Normally, as long as bob can authenticate himself, the authpf program will load the appropriate 
rules. Enter the /etc/authpf/banned/ directory. If bob has somehow fallen from grace in the eyes of 
the powers-that-be, they can prohibit him from using the gateway by creating the file 
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/etc/authpf/banned/bob containing a message about why he has been banned from using the net¬ 
work. Once bob has done suitable penance, his access may be restored by moving or removing the file 

/etc/authpf/banned/bob. 

Now consider a workgroup containing alice, bob, carol and dave. They have a wireless network which they 
would like to protect from unauthorized use. To accomplish this, they create the file 
/etc/authpf/authpf .allow which lists their login ids, one per line. At this point, even if eve could 
authenticate to sshd(8), she would not be allowed to use the gateway. Adding and removing users from the 
work group is a simple matter of maintaining a list of allowed userids. If bob once again manages to annoy 
the powers-that-be, they can ban him from using the gateway by creating the familiar 
/etc/authpf/banned/bob file. Though bob is listed in the allow file, he is prevented from using this 
gateway due to the existence of a ban file. 

Distributed Authentication - It is often desirable to interface with a distributed password system rather than 
forcing the sysadmins to keep a large number of local password files in sync. The login . conf(5) mecha¬ 
nism in OpenBSD can be used to fork the right shell. To make that happen, login. conf(5) should have 
entries that look something like this: 

she11-default:shell=/bin/csh 
default:\ 

:she11=/usr/sbin/authpf 


daemon:\ 


:shell=/bin/csh:\ 
:tc=default: 


staff:\ 


:shell=/bin/csh:\ 

:tc=default: 

Using a default password file, all users will get authpf as their shell except for root who will get 

/bin/csh. 

SSH Configuration - As stated earlier, sshd(8) must be properly configured to detect and defeat network 
attacks. To that end, the following options should be added to sshd_conf ig(5): 

ClientAlivelnterval 15 
ClientAliveCountMax 3 

This ensures that unresponsive or spoofed sessions are terminated within a minute, since a hijacker should 
not be able to spoof ssh keepalive messages. 

Banners - Once authenticated, the user is shown the contents of /etc/authpf/authpf .message. This 
message may be a screen-full of the appropriate use policy, the contents of /etc/motd or something as 
simple as the following: 

This means you will be held accountable by the powers that be 
for traffic originating from your machine, so please play nice. 

To tell the user where to go when the system is broken, /etc/authpf/authpf . problem could contain 
something like this: 
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Sorry, there appears to be some system problem. To report this 
problem so we can fix it, please phone 1-900-314-1597 or send 
an email to remove@bulkmailerz.net. 

Packet Filter Rules - In areas where this gateway is used to protect a wireless network (a hub with several 
hundred ports), the default rule set as well as the per-user rules should probably allow very few things be¬ 
yond encrypted protocols like ssh(l), ssl(8), or ipsec(4). On a securely switched network, with plug-in 
jacks for visitors who are given authentication accounts, you might want to allow out everything. In this con¬ 
text, a secure switch is one that tries to prevent address table overflow attacks. The examples below' assume a 
switched wired net. 

Example /etc/pf . conf: 

# by default we allow internal clients to talk to us using 

# ssh and use us as a dns server, 
internal_if="fxpl" 
gateway_addr="10.0.1.1" 
nat-anchor authpf 

rdr-anchor authpf 
binat-anchor authpf 

block in on $internal_if from any to any 

pass in quick on $internal_if proto tcp from any to $gateway_addr \ 
port = ssh 

pass in quick on $internal_if proto udp from any to $gateway_addr \ 
port = domain 
anchor authpf 

Example /etc/authpf /authpf . rules: 

# no real restrictions here, basically turn the network jack off or on. 

external_if = "xlO" 
internal_if = "fxpO" 

pass in log quick on $internal_if proto tcp from $user_ip to any \ 
keep state 

pass in quick on $internal_if from $user_ip to any 

Another example /etc/authpf/authpf . rules for an insecure network (such as a public wireless net¬ 
work) where we might need to be a bit more restrictive. 

internal_if="fxpl" 
ipsec_gw="10.2.3.4" 

# rdr ftp for proxving by ftp-proxy(8) 

rdr on $internal__if proto tcp from $user_ip to any port 21 \ 

-> 127.0.0.1 port 8081 

# allow out ftp, ssh, www and https only, and allow user to negotiate 

# ipsec with the ipsec server. 

pass in log quick on $internal_if proto tcp from $user_ip to any \ 
port { 21, 22, 80, 443 } flags S/SA 

pass in quick on $internal_if proto tcp from $user_ip to any \ 
port { 21, 22, 80, 443 } 

pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp \ 
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keep state 

pass in quick proto esp from $user_ip to $ipsec_gw 


FILES 

/etc/authpf/authpf.conf 
/etc/authpf/authpf.allow 
/etc/authpf/authpf.rules 
/etc/authpf/authpf.message 
/etc/authpf/authpf.problem 

SEE ALSO 

pf(4), pf . conf(5), ftp-proxy(8) 


BUGS 

authpf does not support binat translation rules. 

Configuration issues are tricky. The authenticating ssh(l) connection may be secured, but if the network is 
not secured the user may expose insecure protocols to attackers on the same network, or enable other attack¬ 
ers on the network to pretend to be the user by spoofing their IP address. 

authpf is not designed to prevent users from denying service to other users. 

HISTORY 

The authpf program first appeared in OpenBSD 3.1. 

COPYRIGHT 

Copyright (c) 2002 Bob Beck (beck@openbsd.org>. All rights reserved. 

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met: 

1. Redistributions of source code must retain the above copyright 
notice, this list of conditions and the following disclaimer. 

2. Redistributions in binary form must reproduce the above copyright 
notice, this list of conditions and the following disclaimer in the 
documentation and/or other materials provided with the distribution. 

3. The name of the author may not be used to endorse or promote products 
derived from this software without specific prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE AUTHOR “AS IS” AND ANY EXPRESS OR 
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 

IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 

INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 

DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
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NAME 

ftp-proxy - Internet File Transfer Protocol proxy server. 

SYNOPSIS 

ftp-proxy [ -AnrVw] [ -D debuglevel) [ -g group] [ -m minport] [ -M maxport] [ -t 
timeout] [-u user] 

DESCRIPTION 

ftp-proxy is a proxy for the Internet File Transfer Protocol. The proxy uses pf(4) and expects to have 
the FTP control connection as described in services(5) redirected to it via a pf (4) rdr command. An ex¬ 
ample of how to do that is further down in this document. 

The options are as follows: 

-A Permit only anonymous FTP connections. The proxy will allow connections to log in to other sites 
as the user "ftp" or "anonymous” only. Any attempt to log in as another user will be blocked by the 
proxy. 

-D debuglevel 

Specify a debug level, where the proxy emits verbose debug output into syslogd(8) at level 
LOG_DEBUG. Meaningful values of debuglevel are 0-3, where 0 is no debug output and 3 is lots 
of debug output, the default being 0. 

-g group 

Specify the named group to drop group privileges to, after doing pf(4) lookups which require root. 
By default ftp-proxy uses the default group of the user it drops privilege to. 

-m minport 

Specify the lower end of the port range the proxy will use for all data connections it establishes. 
The default is IPPORT_HIFIRSTAUTO defined in <netinet/in.h> as 49152. 

-M maxport 

Specify the upper end of the port range the proxy will use for the data connections it establishes. 
The default is IPPORT_HILASTAUTO defined in <netinetyin.h> as 65535. 

-n Activate network address translation mode. In this mode, the proxy will not attempt to proxy pas¬ 
sive mode (PASV or EPSV) data connections. In order for this to work, the machine running the 
proxy will need to be forwarding packets and doing network address translation to allow the out¬ 
bound passive connections from the client to reach the server. See pf . conf(5) for more details on 
nat. The proxy only ignores passive mode data connections when using this flag, it will still proxy 
PORT and EPRT mode data connections. Without this flag, ftp-proxy does not require any IP 
forwarding or NAT beyond the rdr necessary to capture the FTP control connection. 

-r Use reverse host (reverse DNS) lookups for logging and libwrap use. By default the proxy does not 
look up hostnames for libwrap or logging purposes. 

-t timeout 

Specifies a timeout, in seconds. The proxy will exit and close open connections if it sees no data for 
the duration of the timeout. The default is 0, which means the proxy will not time out. 

-u user 

Specify the named user to drop privilege to, after doing pf (4) lookups which require root privilege. 
By default ftp-proxy drops privilege to the user proxy \ 

Running as root means that the source of data connections the proxy makes for PORT and EPRT 
will be the RFC mandated port 20. When running as a non-root user the source of the data connec- 
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tions from ftp-proxy will be chosen randomly from the range minport to maxport as de¬ 
scribed below. 

-V Be verbose. With this option the proxy logs the control commands sent by clients and the replies 
sent by the servers to syslogd(8) 

-w Use the tcp wrapper access control library hosts_access(3) allowing connections to be allowed 
or denied based on the tcp wrapper's hosts . allow(5) and hosts. deny(5) files. The proxy 
does libwrap operations after determining the destination of the captured control connection, so that 
tcp wrapper rules may be written based on the destination as well as the source of FTP connections. 

ftp-proxy is run from inetd(8) and requires that FTP connections are redirected to it using a rdr rule. 

A typical way to do this would be to use a pf . conf (5) rule such as 


int_if = xlO 

rdr on $int_if proto tcp from any to any port 21 -> 127.0.0.1 port 8021 
inetd(8) must then be configured to run ftp-proxy on the port from above using 
127.0.0.1:8021 stream tcp nowail root /usr/libexec/ftp-proxy ftp-proxy 

in inetd.conf(5). 

ftp-proxy accepts the redirected control connections and forwards them to the server. The proxy replaces 
the address and port number that the client sends through the control connection to the server with his own 
address and proxy port, where it listens for the data connection. When the server opens the data connection 
back to this port, the proxy forwards it to the client. The pf . conf(5) rules need to let pass connections to 
these proxy ports (see options -u, -m and -M above) in on the external interface. The following example al¬ 
lows only ports 49152 to 65535 to pass in statefully: 

block in on $ext_if proto tcp all 

pass in on $ext_if inet proto tcp from any to $ext_if \ 
port > 49151 keep state 

Alternatively, rules can make use of the fact that by default, ftp-proxy runs as user "proxy" to allow the 
backchannel connections, as in the following example: 

block in on $ext_if proto tcp all 

pass in on $ext_if inet proto tcp from any to $ext_if \ 
user proxy keep state 

These examples do not cover the connections from the proxy to the foreign ftp server. If one does not pass 
outgoing connections by default additional rules are needed. 

SEE ALSO 

ftp(l), pf(4), hosts . allow(5), hosts . deny(5), inetd. conf(5), pf . conf(5), inetd(8), 
pfctl(8), syslogd(8). 


BUGS 

Extended Passive mode (EPSV) is not supported by the proxy and will not work unless the proxy is run in 
network address translation mode. When not in network address translation mode, the proxy returns an error 
to the client, hopefully forcing the client to revert to Passive mode (PASV) which is supported. EPSV will 
work in network address translation mode, assuming a pf .conf(5) setup which allows the EPSV connec¬ 
tions through to their destinations. 
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IPv6 is not yet supported. 

COPYRIGHT 

Copyright (c) 1996-2001 Obtuse Systems Corporation, All rights reserved. 

Redistribution and use in source and binary forms, with or without 

modification, are permitted provided that the following conditions 

are met: 

1. Redistributions of source code must retain the above copyright 
notice, this list of conditions and the following disclaimer. 

2. Redistributions in binary form must reproduce the above copyright 
notice, this list of conditions and the following disclaimer in the 
documentation and/or other materials provided with the distribution. 

3. Neither the name of the University nor the names of its contributors 
may be used to endorse or promote products derived from this software 
without specific prior written permission. 


THIS SOFTWARE IS PROVIDED BY OBTUSE SYSTEMS AND CONTRIBUTORS “AS IS” AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
ARE DISCLAIMED. IN NO EVENT SHALL OBTUSE OR CONTRIBUTORS BE LIABLE 
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
DAMAGES (INCLUDING. BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 

HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
SUCH DAMAGE. 
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NAME 

pfctl - control the packet filter (PF) and network address translation 

SYNOPSIS 

pfctl [ -AdeghnNqrROvz] [ -a anchor[:ruleset ]] [ -D macro=value] [- f file] 

[-F modifier] { - k host][-s modifier] [-t table] 

[ -T command [address ...]][ — x level] 

DESCRIPTION 

The pf ctl utility communicates with the packet filter device using the ioctl interface described in pf (4). It 
allows ruleset and parameter configuration and retrieval of status information from the packet filter. 

Packet filtering restricts the types of packets that pass through network interfaces entering or leaving the host 
based on filter rules as described in pf. conf(5). The packet filter can also replace addresses and ports of 
packets. Replacing source addresses and ports of outgoing packets is called NAT (Network Address Transla¬ 
tion) and is used to connect an internal network (usually reserved address space) to an external one (the Inter¬ 
net) by making all connections to external hosts appear to come from the gateway. Replacing destination ad¬ 
dresses and ports of incoming packets is used to redirect connections to different hosts and/or ports. A com¬ 
bination of both translations, bidirectional NAT, is also supported. Translation rules are described in 
pf. conf(5). 

When the variable pf is set to YES in rc . conf (8), the rule file specified with the variable pf_rules is loaded 
automatically by the rc(8) scripts and the packet filter is enabled. 

The packet filter does not itself forward packets between interfaces. Forwarding can be enabled by setting 
the sysctl(8) variables net.inet.ip.forwarding and/or net.inet6.ip6.forwarding , to 1. Set them permanently 
in sysct 1. conf(5). 

The pf ctl utility provides several commands. The options are as follows: 

-a anchor[:ruleset] 

Apply flags -f, -F and -s only to the rules in the specified anchor and optional named ruleset 
ruleset. In addition to the main ruleset, pfctl can load and manipulate additional rulesets by 
name. Named rulesets are attached at anchor points, which are also referenced by name. Evalua¬ 
tion of anchor rules from the main ruleset is described in pf. conf(5). For example, to show all 
filter rules inside anchor f oo: 

# pfctl -a foo -s rules 

-A Load only the queue rules present in the rule file. Other rules and options are ignored. 

-d Disable the packet filter. 

-D macro=value 

Define macro to be set to value on the command line. Overrides the definition of macro in the 
ruleset. 

-e Enable the packet filter. 

-f file 

Load the rules contained in file . This file may contain macros, tables, options, and normaliza¬ 
tion, queueing, translation, and filtering rules. With the exception of macros and tables, the state¬ 
ments must appear in that order. 

-F modifier 
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Flush the filter parameters specified by modifier (may be abbreviated): 


-F 

nat 

Flush the NAT rules. 

-F 

queue 

Flush the queue rules. 

-F 

rules 

Flush the filter rules. 

-F 

state 

Flush the state table (NAT and filter). 

-F 

info 

Flush the filter information (statistics that are not bound to rules). 

-F 

Tables 

Flush the tables. 

-F 

all 

Flush all of the above. 


-g Include output helpful for debugging. 

-k host 

Kill all of the state entries originating from the specified host. A second -k host option may be 
specified, which will kill all the state entries from the first host to the second host. For example, 
to kill all of the state entries originating from host: 

# pfctl -k host 

To kill all of the state entries from hostl to host2: 


# pfctl -k hostl -k host2 

-h Help. 

-n Do not actually load rules, just parse them. 

-N Load only the NAT rules present in the rule file. Other rules and options are ignored, 

-q Only print errors and warnings. 

-r Perform reverse DNS lookups on states when displaying them. 

-R Load only the filter rules present in the rule file. Other rules and options are ignored. 

-O Load only the options present in the rule file. Other rules and options are ignored. 


-s modifier 


Show the filter parameters specified by modifier (may be abbreviated): 

-s nat Show the currently loaded NAT rules. 

-s queue Show the currently loaded queue rules. When used together with -v, per-queue 

statistics are also shown. When used together with -v -v, pfctl will loop 
and show updated queue statistics every five seconds, including measured band¬ 
width and packets per second. 


-s rules 

-s Anchors 

-s state 
-s info 
~~s labels 

-s timeouts 


Show the currently loaded filter rules. When used together with -v, the per-rule 
statistics (number of evaluations, packets and bytes) are also shown. Note that 
the ’skip step’ optimization done automatically by the kernel will skip evaluation 
of rules where possible. Packets passed statefully are counted in the rule that 
created the state (even though the rule isn’t evaluated more than once for the en¬ 
tire connection). 

Show the currently loaded anchors. If -a anchor is specified as well, the 
named rulesets currently loaded in the specified anchor are shown instead. 

Show the contents of the state table. 

Show filter information (statistics and counters). 

Show per-rule statistics (in terse format) of filter rules with labels, useful for ac¬ 
counting. 

Show the current global timeouts. 
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HISTORY 

The pf ctl program and the pf(4) filter mechanism first appeared in OpenBSD 3.0. 


COPYRIGHT 

Copyright (c) 2001 Kjell Wooding. All rights reserved. 


Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met: 

1. Redistributions of source code must retain the above copyright 
notice, this list of conditions and the following disclaimer. 

2. Redistributions in binary form must reproduce the above copyright 
notice, this list of conditions and the following disclaimer in the 
documentation and/or other materials provided with the distribution. 

3. The name of the author may not be used to endorse or promote products 
derived from this software without specific prior written permission. 


THIS SOFTWARE IS PROVIDED BY THE AUTHOR “AS IS" AND ANY EXPRESS OR 
IMPLIED WARRANTIES, INCLUDING. BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
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NAME 

pf logd - packet filter logging daemon 

SYNOPSIS 

pflogd [ -D] [ -d delay] [-f filename ][-s snaplen][expression] 

DESCRIPTION 

pflogd is a background daemon which reads packets logged by pf(4) to the packet logging interface 
pf logO and writes the packets to a logfile (normally /var/log/pf log) in tcpdump(8) binary format. 
These logs can be reviewed later using the -r option of tcpdump(8), hopefully offline in case there are 
bugs in the packet parsing code of tcpdump(8). 

pflogd closes and then re-opens the log file when it receives S1GHUP , permitting newsyslog(8) to rotate 
logfiles automatically. S1GALRM causes pflogd to flush the current logfile buffers to the disk, thus making 
the most recent logs available. The buffers are also flushed every delay seconds. 

If the log file contains data after a restart or a S1GHUP , new logs are appended to the existing file. If the ex¬ 
isting log file was created with a different snaplen, pflogd temporarily uses the old snaplen to keep the log 
file consistent. 

The options are as follows: 

-d delay 

Time in seconds to delay between automatic flushes of the file. This may be specified with a value 
between 5 and 3600 seconds. If not specified, the default is 60 seconds. 

-D Debugging mode, pflogd does not disassociate from the controlling terminal. 

-f filename 

Log output filename. Default is /var/log/pf log. 

-s snaplen 

Analyze at most the first snaplen bytes of data from each packet rather than the default of 96. 
The default of 96 is adequate for IP, ICMP, TCP, and UDP headers but may truncate protocol infor¬ 
mation for other protocols. Other file parsers may desire a higher snaplen. 

expression 

Selects which packets will be dumped, using the regular language of tcpdump(8). 


EXAMPLES 

Log specific tcp packets to a different log file with a large snaplen (useful with a log-all rule to dump com¬ 
plete sessions) 

# pflogd -s 1600 -f suspicious.log port 80 and host evilhost 

Display binary logs: 

# tcpdump -n -e -ttt -r /var/log/pflog 

Display the logs in real time (this does not interfere with the operation of pflogd): 

# tcpdump -n -e -ttt -i pflogO 

Tcpdump has been extended to be able to filter on the pfloghdr structure defined in <net/if_pflog.h>. 
Tcpdump can restrict the output to packets logged on a specified interface, a rule number, a reason, a direc¬ 
tion, an ip family or an action. 
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PFLOGD(8) 


OpenBSD System Manager’s Manual 


PFLOGD(8) 


ifname kueO 
on kueO 


»P 

ip6 


rulenum 10 
reason match 


Address family equals IPv4. 
Address family equals IPv6. 
Interface name equals "kueO" 
Interface name equals "kueO" 
Rule number equals 10. 


action pass 

inbound 

outbound 


Reason equals match. Also accepts "bad-offset", "fragment", "short", "normalize" and 
"memory". 

Action equals pass. Also accepts "block". 


The direction was inbound. 
The direction was outbound. 


Display the logs in real time of inbound packets that were blocked on the wiO interface: 

# tcpdump -n -e -ttt -i pflogO inbound and action block and on wiO 


FILES 


/var/run/pf logd.pid Process ID of the currently running pflogd. 
/var/log/pf log Default log file. 


SEE ALSO 

pcap(3), pf(4), pf log(4), pf . conf(5), newsyslog(8), tcpdump(8) 

AUTHORS 

Can Erkin Acar 

HISTORY 

The pflogd command appeared in OpenBSD 3.0. 

COPYRIGHT 

Copyright (c) 2001 Can Erkin Acar. All rights reserved. 

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met: 

1. Redistributions of source code must retain the above copyright 
notice, this list of conditions and the following disclaimer. 

2. Redistributions in binary form must reproduce the above copyright 
notice, this list of conditions and the following disclaimer in the 
documentation and/or other materials provided with the distribution. 

3. The name of the author may not be used to endorse or promote products 
derived from this software without specific prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE AUTHOR “AS IS” AND ANY EXPRESS OR 
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
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